Developer CD Series 1998 November: Tool Chest/Dev.CD Nov 98 TC.toast/Sample Code/Networking/StreamNOP1.0b2/StreamNOP.c

Text File | 1998-07-13 | 12.6 KB | 424 lines | [TEXT/CWIE]

/*
    File:        StreamNOP.c

    Contains:    Stream module that does nothing.

    Written by:    Quinn "The Eskimo!"

    Copyright:    © 1997-1998 by Apple Computer, Inc., all rights reserved.

    Change History (most recent first):

    You may incorporate this sample code into your applications without
    restriction, though the sample code has been provided "AS IS" and the
    responsibility for its operation is 100% yours.  However, what you are
    not permitted to do is to redistribute the source as "DSC Sample Code"
    after having made changes. If you're going to re-distribute the source,
    we require that you make it clear in the source that the code was
    descended from Apple Sample Code, but that you've made changes.
*/

/////////////////////////////////////////////////////////////////////
// The OT debugging macros in <OTDebug.h> require this variable to
// be set.

#ifndef qDebug
#define qDebug    1
#endif

/////////////////////////////////////////////////////////////////////
// Determine whether this is going to be an instrumented build or not.

#ifndef INSTRUMENTATION_ACTIVE
    #define INSTRUMENTATION_ACTIVE 0
#else
    #define INSTRUMENTATION_ACTIVE 1
#endif

/////////////////////////////////////////////////////////////////////
// Pick up all the standard OT module stuff.

#include <OpenTptModule.h>

/////////////////////////////////////////////////////////////////////
// Pick up the OTDebugBreak and OTAssert macros.

#include <OTDebug.h>

/////////////////////////////////////////////////////////////////////
// Pick up all the standard TPI/DLPI constants and structures.

#include <tihdr.h>
#include <dlpi.h>

/////////////////////////////////////////////////////////////////////
// Pick up Instrumentation SDK stuff.  We only do this if we're
// actually instrumenting, so you don't even have to have the SDK
// to compile the non-instumented version of the code.  If we're
// not instrumenting, we compile a bunch of bogus macros that generally
// compile to nothing.

#if INSTRUMENTATION_ACTIVE
    #include <InstrumentationMacros.h>
#else
    #define TRACE_SETUP        long __junk
    #define LOG_ENTRY(n)    if (0) { __junk ; }
    #define LOG_EXIT        if (0) { __junk ; }
#endif

/////////////////////////////////////////////////////////////////////
// OTDebugStr is not defined in any OT header files, but it is
// exported by the libraries, so we define the prototype here.

extern pascal void OTDebugStr(const char* str);

/////////////////////////////////////////////////////////////////////
// Some simple routines we use in our various assertions.

static Boolean IsReadQ(queue_t* q)
    // Returns true if q is the read queue of a queue pair.
{
    return ( (q->q_flag & QREADR) != 0 );
}

static Boolean IsWriteQ(queue_t* q)
    // Returns true if q is the write queue of a queue pair.
{
    return ( (q->q_flag & QREADR) == 0 );
}

/////////////////////////////////////////////////////////////////////
// Per-Stream information

// This structure is used to hold the per-stream data for the module.
// While module's can use normal global variables to store real globals,
// they must maintain their own per-stream data structures.  I use
// mi_open_comm to allocate this data structure when the stream is
// opened.  mi_open_comm stores the address of this data structure in the
// read and write queue's q_ptr field, so the rest of the code
// can get to it by calling the GetPerStreamData function.

enum {
    kStreamNOPPerStreamDataMagic = 'NOOP'
};

struct PerStreamData
{
    OSType                 magic;                // kStreamNOPPerStreamDataMagic = 'NOOP' for debugging
    // Your per-stream data structures go here.
};
typedef struct PerStreamData PerStreamData, *PerStreamDataPtr;

static PerStreamDataPtr GetPerStreamData(queue_t* readOrWriteQ)
    // You can pass both the read or the write queue to this routine
    // because mi_open_comm sets up both q_ptr's to point to the
    // queue local data.
    //
    // Note that, in order to avoid the overhead of a function call,
    // you would normally use inline code (or a macro)
    // to get your per-stream data instead of using a separate function.
    // However I think the separate function makes things clearer.
    // I also acts as a central bottleneck for my debugging code.
    //
    // Environment: any standard STREAMS entry point
{
    PerStreamDataPtr streamData;

    streamData = (PerStreamDataPtr) readOrWriteQ->q_ptr;

    OTAssert("GetPerStreamData: what streamData", streamData != nil);
    OTAssert("GetPerStreamData: Bad magic", streamData->magic == kStreamNOPPerStreamDataMagic);

    return (streamData);
}

// mi_open_comm and mi_close_comm (and also mi_detach and mi_close_detached)
// use this global to store the list of open streams to this module.

static char* gStreamList = nil;

/////////////////////////////////////////////////////////////////////
// Open routine

static int StreamNOPOpen(queue_t* rdq, dev_t* dev, int flag, int sflag, cred_t* creds)
    // This routine is called by STREAMS when a new stream is connected to
    // our module.  The bulk of the work here is done by the Mentat helper
    // routine mi_open_comm.
    //
    // Environment: standard STREAMS entry point
{
    TRACE_SETUP;
    int err;
    PerStreamDataPtr streamData;

    LOG_ENTRY( "StreamNOP:StreamNOPOpen" );

    OTAssert("StreamNOPOpen: Not the read queue", IsReadQ(rdq) );

    OTDebugBreak("StreamNOPOpen");

    err = noErr;

    // If we already have per-stream data for this stream, the stream is being reopened.
    // In that case, we can just return.
    // Note that we can't call GetPerStreamData because it checks that streamData is not nil.

    if ( rdq->q_ptr != nil ) {
        goto done;
    }

    // Make sure we're being opened properly -- because we're a module we
    // require a "module" open.  Other possibilities are the value 0 (used
    // to open a specific minor device number (ie stream) on a device driver),
    // and CLONEOPEN (used to open a new stream to a device number where you
    // don't care what device number you get -- the typical behaviour for
    // networking (as opposed to serial) devices).

    if ( (err == noErr) && (sflag != MODOPEN) ) {
        err = ENXIO;
    }

    // Use the mi_open_comm routine to allocate our per-stream data.  Then
    // zero out the entire per-stream data record and fill out the fields
    // we're going to need.

    if (err == noErr) {
        err = mi_open_comm(&gStreamList, sizeof(PerStreamData), rdq, dev, flag, sflag, creds);
        if ( err == noErr ) {
            // Note that we can't call GetPerStreamData because the magic is not set up yet.
            streamData = (PerStreamDataPtr) rdq->q_ptr;

            OTMemzero(streamData, sizeof(PerStreamData));

            streamData->magic = kStreamNOPPerStreamDataMagic;
        }
    }

done:
    LOG_EXIT;
    return (err);
}

/////////////////////////////////////////////////////////////////////
// Close routine

static int StreamNOPClose(queue_t* rdq, int flags, cred_t* credP)
    // This routine is called by STREAMS when a stream is being
    // disconnected from our module (ie closed).  The bulk of the work
    // is done by the magic Mentat helper routine mi_close_comm.
    //
    // Environment: standard STREAMS entry point
{
    TRACE_SETUP;
    #pragma unused(flags)
    #pragma unused(credP)

    LOG_ENTRY( "StreamNOP:StreamNOPClose" );

    OTAssert("StreamNOPClose: Not the read queue", IsReadQ(rdq) );

    (void) mi_close_comm(&gStreamList, rdq);

    LOG_EXIT;
    return (0);
}

/////////////////////////////////////////////////////////////////////

enum {
    kNoPrimitive = -1
};

static long GetPrimitive(mblk_t* mp)
    // GetPrimitive gets the TPI/DLPI primitive out of a message block.
    // It returns kNoPrimitive if the message block is of the wrong
    // type or there is no primitive.
    //
    // Environment: any standard STREAMS entry point
{
    if ((mp->b_datap->db_type == M_PROTO || mp->b_datap->db_type == M_PCPROTO) && MBLK_SIZE(mp) >= sizeof(long) ) {
        return ( ( (union T_primitives*) mp->b_rptr)->type );
    } else {
        return ( kNoPrimitive );
    }
}

/////////////////////////////////////////////////////////////////////
// Write-side put routine

static int StreamNOPWritePut(queue_t* q, mblk_t* mp)
    // This routine is called by STREAMS when it has a message for our
    // module from upstream.  Typically, this routine is a big case statement
    // that dispatches to our various message handling routines.  However, the
    // function of this stream module is to pass through all messages unchanged,
    // so the case statement is not very exciting.
    //
    // Environment: standard STREAMS entry point
{
    TRACE_SETUP;
    PerStreamDataPtr streamData;

    LOG_ENTRY( "StreamNOP:StreamNOPWritePut" );

    OTAssert("StreamNOPWritePut: Not the write queue", IsWriteQ(q) );

    // OTDebugBreak("StreamNOPWritePut: Entered");

    streamData = GetPerStreamData(q);

    switch ( GetPrimitive(mp) ) {
        default:
            putnext(q, mp);
            break;
    }

    LOG_EXIT;

    return 0;
}

/////////////////////////////////////////////////////////////////////
// Read-side put routine

static int StreamNOPReadPut(queue_t* q, mblk_t* mp)
    // This routine is called by STREAMS when it has a message for our
    // module from downstream.  Typically, this routine is a big case statement
    // that dispatches to our various message handling routines.  However, the
    // function of this stream module is to pass through all messages unchanged,
    // so the case statement is not very exciting.
    //
    // Environment: standard STREAMS entry point
{
    TRACE_SETUP;
    PerStreamDataPtr streamData;

    LOG_ENTRY( "StreamNOP:StreamNOPReadPut" );

    OTAssert("StreamNOPReadPut: Not the read queue", IsReadQ(q) );

    // OTDebugBreak("StreamNOPReadPut: Entered");

    streamData = GetPerStreamData(q);

    switch ( GetPrimitive(mp) ) {
        default:
            putnext(q, mp);
            break;
    }

    LOG_EXIT;

    return 0;
}

/////////////////////////////////////////////////////////////////////
// Static Declaration Structures

static struct module_info gModuleInfo =
{
    9992,                        // Module Number, only useful for debugging
    "StreamNOP",                // Name of module
    0,                            // Minimum data size
    INFPSZ,                        // Maximum data size
    16384,                        // Hi water mark for queue
    4096                        // Lo water mark for queue
};

static struct qinit gReadInit =
{
    StreamNOPReadPut,        // Put routine for "incoming" data
    nil,                        // Service routine for "incoming" data
    StreamNOPOpen,            // Our open routine
    StreamNOPClose,         // Our close routine
    nil,                        // No admin routine
    &gModuleInfo                // Our module_info
};

static struct qinit gWriteInit =
{
    StreamNOPWritePut,        // Put routine for client data
    nil,                        // Service routine for client data
    nil,                        // open  field only used in read-side structure
    nil,                        // close field only used in read-side structure
    nil,                        // admin field only used in read-side structure
    &gModuleInfo                // Our module_info
};

static struct streamtab theStreamTab =
{
    &gReadInit,                    // Our read-side qinit structure
    &gWriteInit,                // Our write-side qinit structure
    0,                            // We are not a mux, so set this to nil
    0                            // We are not a mux, so set this to nil
};

/////////////////////////////////////////////////////////////////////
// Macintosh-specific Static Structures

static struct install_info theInstallInfo =
{
    &theStreamTab,            // Stream Tab pointer
    kOTModIsModule + kOTModUpperIsTPI + kOTModIsFilter,
                            // Tell OT that we are a driver, not a module
    SQLVL_MODULE,            // Synchronization level, module level for the moment
    0,                        // Shared writer list buddy
    0,                        // Open Transport use - always set to 0
    0                        // Flag - always set to 0
};

// Prototypes for the exported routines below.

extern Boolean InitStreamModule(void *portInfo);
extern void TerminateStreamModule(void);
extern install_info* GetOTInstallInfo();

#pragma export list GetOTInstallInfo, InitStreamModule, TerminateStreamModule

// Export entry point

extern Boolean InitStreamModule(void *portInfo)
    // Initialises the module before the first stream is opened.
    // Should return true if the module has started up correctly.
    //
    // Environment: Always called at SystemTask time.
{
    TRACE_SETUP;
    #pragma unused(portInfo)
    Boolean result;

    OTDebugBreak("StreamNOP: InitStreamModule");

    LOG_ENTRY( "StreamNOP:InitStreamModule" );

    result = true;

    LOG_EXIT;
    return (result);
}

extern void TerminateStreamModule(void)
    // Shuts down the module after the last stream has been
    // closed.
    //
    // Environment: Always called at SystemTask time.
{
    TRACE_SETUP;

    LOG_ENTRY( "StreamNOP:TerminateStreamModule" );

    // It's an excellent idea to have the following in your code, just to make
    // sure you haven't left any streams open before you quit.  In theory, OT
    // should not call you until the last stream has been closed, but in practice
    // this can happen if you use mi_detach to half-close a stream.

    OTAssert("TerminateStreamModule: Streams are still active", gStreamList == nil);

    LOG_EXIT;
}

extern install_info* GetOTInstallInfo()
    // Return pointer to install_info to STREAMS.
{
    return &theInstallInfo;
}